wqueue: Support custom user work queues. - #19982
Open
13022591351 wants to merge 4 commits into
Open
Conversation
13022591351
requested review from
Donny9,
GUIDINGLI,
hartmannathan,
jerpelea,
pkarashchenko and
xiaoxiang781216
as code owners
August 27, 2026 08:47
This was referenced Aug 27, 2026
github-actions
Bot
added
Area: Documentation
|
13022591351
force-pushed
the
feature/custom-user-wqueue
branch
from
August 27, 2026 12:54
9dd9a74 to
d3b65e9
Compare
Contributor
Author
|
Updated the series organization and repeated the complete master hardware The series is now split into scheduler functionality, libc functionality with Fresh Three USB NSH runs per backend: All assertions passed. Steady-state heap usage remained unchanged after the The final PR WQ source tree matches the runtime-tested source tree. Full-range |
Prevent work_queue_free() from destroying predefined queues or freeing a custom queue from one of its own callbacks. Mark teardown under the queue lock, reject new submissions, return pending work to its owner, and wait for every worker before releasing queue resources. Clean up partially created worker pools, reject invalid delays, safely replace pending periodic work, and make synchronous cancellation wait for every concurrent callback using the same work structure. Tested on an STM32H7 PX4 FMUv6C with the matching ostest suite in Flat and Protected kernel builds. Assisted-by: Codex:GPT-5 Signed-off-by: DuoYuWang <thirteenking.wang@gmail.com>
Implement the handle-based create, queue, priority, cancellation, and teardown APIs for CONFIG_LIBC_USRWORK. Custom queues use configurable pthread worker pools while the predefined USRWORK queue remains available. Match scheduler-backend delay, replacement, cancellation, and lifecycle semantics. Restrict the libc backend to task context because it uses blocking synchronization. Tested on an STM32H7 PX4 FMUv6C with ostest wqueue in Protected user space. Assisted-by: Codex:GPT-5 Signed-off-by: DuoYuWang <thirteenking.wang@gmail.com>
Replace the local EINTR retry loop with nxsem_wait_uninterruptible(). This keeps the master implementation aligned with the libc semaphore API without changing cancellation behavior. Keep the cleanup separate so release branches where the helper is not available to Protected user space can use the functional commit without a downstream compatibility patch. Assisted-by: Codex:GPT-5 Signed-off-by: DuoYuWang <thirteenking.wang@gmail.com>
Describe the handle-based custom queue APIs, worker-pool creation and teardown, periodic requeue, cancellation semantics, and return values. Clarify that libc user work queue APIs use blocking synchronization and must only be called from task context, while kernel and Flat queue and asynchronous cancellation operations remain ISR-safe. Assisted-by: Codex:GPT-5 Signed-off-by: DuoYuWang <thirteenking.wang@gmail.com>
13022591351
force-pushed
the
feature/custom-user-wqueue
branch
from
August 29, 2026 13:22
d3b65e9 to
9fc4184
Compare
Contributor
Author
|
I force-pushed the branch after applying the inline review feedback and The updated commit series is: Review fixesThe updated series addresses all 16 inline review comments:
Additional changes beyond the literal inline suggestionsI also included the following compatibility and robustness corrections found
The last scheduling-parameter initialization change is six lines in Test coverageAll full work queue runs cover:
1. FlatBuild output: Three After the first run, Umem remained stable at: The first run retained 32 bytes of one-time process state. The following two 2. ProtectedBuild output: Three kernel backend runs: Three libc custom user queue runs: Steady state after the first executions: The remaining runs had identical current heap usage and allocation-node 3. Protected Lite (
|
| flags = spin_lock_irqsave(&wqueue->lock); | ||
|
|
||
| if (!work_available(work)) | ||
| for (; ; ) |
Contributor
There was a problem hiding this comment.
why need for loop here?
| nxsem_reset(&wqueue->sem, 0); | ||
| nxsem_reset(&wqueue->exsem, 0); | ||
|
|
||
| flags = spin_lock_irqsave_nopreempt(&wqueue->lock); |
| } | ||
|
|
||
| /* Get exclusive access to the work queue */ | ||
| for (; ; ) |
| #ifndef CONFIG_DISABLE_PTHREAD | ||
| int work_queue_priority_wq(FAR struct kwork_wqueue_s *handle) | ||
| { | ||
| return work_priority((FAR struct usr_wqueue_s *)handle); |
Contributor
There was a problem hiding this comment.
merge work_priority here and remove work_priority
| return -EINVAL; | ||
| } | ||
|
|
||
| return work_priority(&g_usrwork); |
Contributor
There was a problem hiding this comment.
call work_queue_priority_wq
| int wndx; | ||
|
|
||
| if (name == NULL || stack_size <= 0 || nthreads < 1 || | ||
| (size_t)nthreads > (SIZE_MAX - sizeof(*wqueue)) / |
Contributor
There was a problem hiding this comment.
remove the cast and merge the next line
| * Name: work_queue_priority_wq | ||
| ****************************************************************************/ | ||
|
|
||
| #ifndef CONFIG_DISABLE_PTHREAD |
| FAR struct usr_worker_s *worker = | ||
| (FAR struct usr_worker_s *)arg; | ||
|
|
||
| while (work_process(worker)) |
Contributor
There was a problem hiding this comment.
merge work_process here and remove work_process
Contributor
|
@13022591351 please fix: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
builds through the existing handle-based work queue API.
libs/libc/wqueuewhileretaining the predefined
USRWORKqueue.submissions during teardown, release pending work ownership, wait for all
workers, clean up partial creation, and synchronously cancel every callback
using the same
work_s.and idempotent cancellation behavior between scheduler and libc backends.
calls to task context; they must not be called from an ISR.
Commit organization
The libc functional commit deliberately contains an explicit
nxsem_wait()retry on-EINTR. The next master-only cleanup commit replacesthat loop with
nxsem_wait_uninterruptible()and produces the same behavior.An older release branch where that helper is not available to Protected user
space can therefore cherry-pick the scheduler and libc functional commits,
omit only the helper cleanup, and take the documentation commit without a
downstream-only compatibility patch.
Please keep the functional and helper-cleanup commits separate for that
reason. If a squashed history is preferred, that older PX4 release branch
will not be supported by this series rather than carrying a special NuttX
patch downstream.
Impact
work queues with configurable priority, stack size, and worker count.
USRWORK,HPWORK, andLPWORKusersremain supported. New user custom-queue APIs are task-context only.
Documentation/reference/os/wqueue.rstand publicheader comments describe custom queues, teardown, errors, and execution
context.
successful no-op, matching the scheduler backend's existing behavior.
Testing
Build host:
Target:
c6b349b0234466a54a624ae35ba77adb73a9ea0epatch-equivalent STM32H7 Protected-memory series from stm32h7: Fix Protected user SRAM placement and attributes. #19983.
make distclean, uploaded throughthe PX4 bootloader, and tested through USB NSH with
minicom.Before change:
Build output after change:
Runtime commands and results, three runs per backend:
Steady-state memory after the first run remained unchanged through all later
runs:
Every run covered one- and two-worker custom queues, explicit caller
priorities, invalid arguments, periodic requeue, pending replacement,
synchronous cancellation, two concurrent callbacks using one
work_s, foursimultaneous queues with 32 work items, self-destruction rejection, and
pending/running teardown. All assertions passed, heap usage did not grow, and
all custom worker pools completed teardown.
The final PR WQ source tree matches the runtime-tested source tree.
Validation:
The documentation HTML build was not run locally because
sphinx-buildisnot installed on the build host.
PR verification Self-Check